Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix inconsistencies in handling of inert attributes on statements #78306

Closed
wants to merge 2 commits into from

Conversation

Aaron1011
Copy link
Member

When the 'early' and 'late' visitors visit an attribute target, they
activate any lint attributes (e.g. #[allow]) that apply to it.
This can affect warnings emitted on sibiling attributes. For example,
the following code does not produce an unused_attributes for
#[inline], since the sibiling #[allow(unused_attributes)] suppressed
the warning.

trait Foo {
    #[allow(unused_attributes)] #[inline] fn first();
    #[inline] #[allow(unused_attributes)] fn second();
}

However, we do not do this for statements - instead, the lint attributes
only become active when we visit the struct nested inside StmtKind
(e.g. Item).

Currently, this is difficult to observe due to another issue - the
HasAttrs impl for StmtKind ignores attributes for StmtKind::Item.
As a result, the unused_doc_comments lint will never see attributes on
item statements.

This commit makes two interrelated fixes to the handling of inert
(non-proc-macro) attributes on statements:

  • The HasAttr impl for StmtKind now returns attributes for
    StmtKind::Item, treating it just like every other StmtKind
    variant. The only place relying on the old behavior was macro
    which has been updated to explicitly ignore attributes on item
    statements. This allows the unused_doc_comments lint to fire for
    item statements.
  • The early and late lint visitors now activate lint attributes when
    invoking the callback for Stmt. This ensures that a lint
    attribute (e.g. #[allow(unused_doc_comments)]) can be applied to
    sibiling attributes on an item statement.

The unused_doc_comments lint now fires on a number of items in the
stnadard library. I've added #[allow(unused_doc_comments)] to these
items.

@rust-highfive
Copy link
Collaborator

r? @petrochenkov

(rust_highfive has picked a reviewer for you, use r? to override)

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Oct 23, 2020
@jyn514 jyn514 added A-attributes Area: #[attributes(..)] A-lint Area: Lints (warnings about flaws in source code) such as unused_mut. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. labels Oct 23, 2020
@Aaron1011
Copy link
Member Author

This lint is firing on a large number of doc comments within the compiler itself. I see several different ways of proceeding:

  1. Convert all of these doc comments to regular comments
  2. Add a blanket #![allow(unused_doc_comments)] to compiler crates.
  3. Add #[allow(unused_doc_comments)] on a case-by-case basis.
  4. Decide that we don't actually want unused_doc_comments to apply to these cases.

cc @rust-lang/rustdoc Is there any reason to have doc comments (as a opposed to regular comments) on a function if it won't be rendered by rustdoc?

@jyn514
Copy link
Member

jyn514 commented Oct 23, 2020

cc rust-lang/rustdoc Is there any reason to have doc comments (as a opposed to regular comments) on a function if it won't be rendered by rustdoc?

@Aaron1011 not that I'm aware of. IMO they should be changed to regular comments (1), but I don't feel very strongly about that.

When the 'early' and 'late' visitors visit an attribute target, they
activate any lint attributes (e.g. `#[allow]`) that apply to it.
This can affect warnings emitted on sibiling attributes. For example,
the following code does not produce an `unused_attributes` for
`#[inline]`, since the sibiling `#[allow(unused_attributes)]` suppressed
the warning.

```rust
trait Foo {
    #[allow(unused_attributes)] #[inline] fn first();
    #[inline] #[allow(unused_attributes)] fn second();
}
```

However, we do not do this for statements - instead, the lint attributes
only become active when we visit the struct nested inside `StmtKind`
(e.g. `Item`).

Currently, this is difficult to observe due to another issue - the
`HasAttrs` impl for `StmtKind` ignores attributes for `StmtKind::Item`.
As a result, the `unused_doc_comments` lint will never see attributes on
item statements.

This commit makes two interrelated fixes to the handling of inert
(non-proc-macro) attributes on statements:

* The `HasAttr` impl for `StmtKind` now returns attributes for
  `StmtKind::Item`, treating it just like every other `StmtKind`
  variant. The only place relying on the old behavior was macro
  which has been updated to explicitly ignore attributes on item
  statements. This allows the `unused_doc_comments` lint to fire for
  item statements.
* The `early` and `late` lint visitors now activate lint attributes when
  invoking the callback for `Stmt`. This ensures that a lint
  attribute (e.g. `#[allow(unused_doc_comments)]`) can be applied to
  sibiling attributes on an item statement.

The `unused_doc_comments` lint now fires on a number of items in the
stnadard library. I've added `#[allow(unused_doc_comments)]` to these
items.
@Mark-Simulacrum Mark-Simulacrum added I-nominated T-lang Relevant to the language team, which will review and decide on the PR/issue. labels Oct 23, 2020
@Mark-Simulacrum
Copy link
Member

Nominating for lang team, I suspect we'll want to just let this go through (it's not really breaking) but it's an interesting question of whether these documentation comments are truly unused.

@Aaron1011
Copy link
Member Author

The 'inner items' message was introduced here: https://github.com/rust-lang/rust/pull/57882/files#diff-38d78212bad0cf87e09d707ee7331a84a049fac2d8b1c7b26584580be81d818aR860-R868

So, it looks like the intention of PR #57882 was to lint doc comments on statement items - this just never worked until now.

@petrochenkov
Copy link
Contributor

r=me on the implementation.

@petrochenkov petrochenkov added S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Oct 24, 2020
@Aaron1011
Copy link
Member Author

I'm going to split out the purely internal changes into a separate PR, with unused_doc_comments explicitly disabled on item statements. This will preserve the current behavior of unused_doc_comments, unblock #78296, and allow the lang team to discuss the behavior of unused_doc_comments.

Aaron1011 added a commit to Aaron1011/rust that referenced this pull request Oct 24, 2020
When the 'early' and 'late' visitors visit an attribute target, they
activate any lint attributes (e.g. `#[allow]`) that apply to it.
This can affect warnings emitted on sibiling attributes. For example,
the following code does not produce an `unused_attributes` for
`#[inline]`, since the sibiling `#[allow(unused_attributes)]` suppressed
the warning.

```rust
trait Foo {
    #[allow(unused_attributes)] #[inline] fn first();
    #[inline] #[allow(unused_attributes)] fn second();
}
```

However, we do not do this for statements - instead, the lint attributes
only become active when we visit the struct nested inside `StmtKind`
(e.g. `Item`).

Currently, this is difficult to observe due to another issue - the
`HasAttrs` impl for `StmtKind` ignores attributes for `StmtKind::Item`.
As a result, the `unused_doc_comments` lint will never see attributes on
item statements.

This commit makes two interrelated fixes to the handling of inert
(non-proc-macro) attributes on statements:

* The `HasAttr` impl for `StmtKind` now returns attributes for
  `StmtKind::Item`, treating it just like every other `StmtKind`
  variant. The only place relying on the old behavior was macro
  which has been updated to explicitly ignore attributes on item
  statements. This allows the `unused_doc_comments` lint to fire for
  item statements.
* The `early` and `late` lint visitors now activate lint attributes when
  invoking the callback for `Stmt`. This ensures that a lint
  attribute (e.g. `#[allow(unused_doc_comments)]`) can be applied to
  sibiling attributes on an item statement.

For now, the `unused_doc_comments` lint is explicitly disabled on item
statements, which preserves the current behavior. The exact locatiosn
where this lint should fire are being discussed in PR rust-lang#78306
@Aaron1011
Copy link
Member Author

@petrochenkov: I've moved the implementation to #78326

JohnTitor added a commit to JohnTitor/rust that referenced this pull request Oct 25, 2020
…rochenkov

Split out statement attributes changes from rust-lang#78306

This is the same as PR rust-lang#78306, but `unused_doc_comments` is modified to explicitly ignore statement items (which preserves the current behavior).

This shouldn't have any user-visible effects, so it can be landed without lang team discussion.

---------
When the 'early' and 'late' visitors visit an attribute target, they
activate any lint attributes (e.g. `#[allow]`) that apply to it.
This can affect warnings emitted on sibiling attributes. For example,
the following code does not produce an `unused_attributes` for
`#[inline]`, since the sibiling `#[allow(unused_attributes)]` suppressed
the warning.

```rust
trait Foo {
    #[allow(unused_attributes)] #[inline] fn first();
    #[inline] #[allow(unused_attributes)] fn second();
}
```

However, we do not do this for statements - instead, the lint attributes
only become active when we visit the struct nested inside `StmtKind`
(e.g. `Item`).

Currently, this is difficult to observe due to another issue - the
`HasAttrs` impl for `StmtKind` ignores attributes for `StmtKind::Item`.
As a result, the `unused_doc_comments` lint will never see attributes on
item statements.

This commit makes two interrelated fixes to the handling of inert
(non-proc-macro) attributes on statements:

* The `HasAttr` impl for `StmtKind` now returns attributes for
  `StmtKind::Item`, treating it just like every other `StmtKind`
  variant. The only place relying on the old behavior was macro
  which has been updated to explicitly ignore attributes on item
  statements. This allows the `unused_doc_comments` lint to fire for
  item statements.
* The `early` and `late` lint visitors now activate lint attributes when
  invoking the callback for `Stmt`. This ensures that a lint
  attribute (e.g. `#[allow(unused_doc_comments)]`) can be applied to
  sibiling attributes on an item statement.

For now, the `unused_doc_comments` lint is explicitly disabled on item
statements, which preserves the current behavior. The exact locatiosn
where this lint should fire are being discussed in PR rust-lang#78306
bors added a commit to rust-lang-ci/rust that referenced this pull request Oct 25, 2020
Rollup of 8 pull requests

Successful merges:

 - rust-lang#77984 (Compute proper module parent during resolution)
 - rust-lang#78085 (MIR validation should check `SwitchInt` values are valid for the type)
 - rust-lang#78208 (replace `#[allow_internal_unstable]` with `#[rustc_allow_const_fn_unstable]` for `const fn`s)
 - rust-lang#78209 (Update `compiler_builtins` to 0.1.36)
 - rust-lang#78276 (Bump backtrace-rs to enable Mach-O support on iOS.)
 - rust-lang#78320 (Link to cargo's `build-std` feature instead of `xargo` in custom target docs)
 - rust-lang#78322 (BTreeMap: stop mistaking node::MIN_LEN for a node level constraint)
 - rust-lang#78326 (Split out statement attributes changes from rust-lang#78306)

Failed merges:

r? `@ghost`
giraffate pushed a commit to giraffate/rust-clippy that referenced this pull request Oct 25, 2020
Split out statement attributes changes from #78306

This is the same as PR rust-lang/rust#78306, but `unused_doc_comments` is modified to explicitly ignore statement items (which preserves the current behavior).

This shouldn't have any user-visible effects, so it can be landed without lang team discussion.

---------
When the 'early' and 'late' visitors visit an attribute target, they
activate any lint attributes (e.g. `#[allow]`) that apply to it.
This can affect warnings emitted on sibiling attributes. For example,
the following code does not produce an `unused_attributes` for
`#[inline]`, since the sibiling `#[allow(unused_attributes)]` suppressed
the warning.

```rust
trait Foo {
    #[allow(unused_attributes)] #[inline] fn first();
    #[inline] #[allow(unused_attributes)] fn second();
}
```

However, we do not do this for statements - instead, the lint attributes
only become active when we visit the struct nested inside `StmtKind`
(e.g. `Item`).

Currently, this is difficult to observe due to another issue - the
`HasAttrs` impl for `StmtKind` ignores attributes for `StmtKind::Item`.
As a result, the `unused_doc_comments` lint will never see attributes on
item statements.

This commit makes two interrelated fixes to the handling of inert
(non-proc-macro) attributes on statements:

* The `HasAttr` impl for `StmtKind` now returns attributes for
  `StmtKind::Item`, treating it just like every other `StmtKind`
  variant. The only place relying on the old behavior was macro
  which has been updated to explicitly ignore attributes on item
  statements. This allows the `unused_doc_comments` lint to fire for
  item statements.
* The `early` and `late` lint visitors now activate lint attributes when
  invoking the callback for `Stmt`. This ensures that a lint
  attribute (e.g. `#[allow(unused_doc_comments)]`) can be applied to
  sibiling attributes on an item statement.

For now, the `unused_doc_comments` lint is explicitly disabled on item
statements, which preserves the current behavior. The exact locatiosn
where this lint should fire are being discussed in PR #78306
@Aaron1011
Copy link
Member Author

The internal rustc changes were merged in #78326. Closing in favor of #78367

@Aaron1011 Aaron1011 closed this Oct 25, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-attributes Area: #[attributes(..)] A-lint Area: Lints (warnings about flaws in source code) such as unused_mut. S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. T-lang Relevant to the language team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants